<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Untitled Document</title>
  <link href="base.css" rel="stylesheet" type="text/css">
</head>

<body>
<div id="fs">

<ul id="menu">
<li><b>Download</b>
<ul>
<li><a href="http://joshy.org/flyingsaucer/downloads/flyingsaucer.src.zip">R5 beta</a></li>
<li><a href="demos.html">demo apps</a></li>
</ul>
</li>
<li><b>Documentation</b>
<ul>
<li><a href="gettingstarted.html"><b>Getting Started</b></a></li>
<li><a href="featurelist.html">Feature List</a></li>
<li><a href="faq.html">The FAQ</a></li>
<li><a href="advanced.html">Developer Guide</a></li>
<li><a href="http://joshy.org/flyingsaucer/doc/user/api/">Simple JavaDocs (R5)</a></li>
<li><a href="http://joshy.org/flyingsaucer/doc/full/api/">Full JavaDocs (R5)</a></li>
<li><a href="../references.html">References</a></li>
</ul>
</li>
<li><b>Contribute</b>
<ul>
<li><a href="https://xhtmlrenderer.dev.java.net/servlets/ProjectMailingListList">dev mailing list</a></li>
<li><a href="https://xhtmlrenderer.dev.java.net/servlets/ProjectMailingListList">user mailing list</a></li>
<li><a href="http://wiki.java.net/bin/view/Javadesktop/XHTMLRenderer">The
Wiki</a></li>
</ul>
</li>
<li id="newsfeed"><b><a href="http://xhtmlrenderer.dev.java.net/servlets/ProjectNewsRSS" border="0">News Feed<img src="https://java-net.dev.java.net/branding/images/xml.gif" border="0"></a></b>
</li>
</ul>


<h1>The Flying Saucer FAQ </h1>

<h3>General</h3>
<ul>
<li><a href="#what_is">What is Flying Saucer?</a></li>
<li><a href="#legacy_html">Does Flying Saucer support legacy HTML?</a></li>
<li><a href="#web_browser">Is Flying Saucer a web browser?</a></li>
<li><a href="#applications">What kind of applications can I use Flying Saucer for?</a></li>
<li><a href="#xhtml_css_support">What XHTML/CSS features does Flying Saucer currently support?</a></li>
<li><a href="#xhtml_css_missing">What XHTML/CSS features is Flying Saucer missing? </a></li>
<li><a href="#hyperlinks">How do I make my program follow hyperlinks?</a></li>
<li><a href="#forms_and_swing">How do I get access to the Swing components that make up my form fields?</a></li>
</ul>

<h3>Developers</h3>
<ul>
<li><a href="#classpath">How do I set up my CLASSPATH?</a></li>
<li><a href="#without_ant">How do I build XR without Ant?</a></li>
<li><a href="#without_ant">How do I build XR from within my IDE?</a></li>
<li><a href="#configuration">How do I change the runtime configuration for XR?</a></li>
<li><a href="#logging">How do I write to the log within XR?</a></li>
</ul>   

<a name="what_is"></a>
<h2>What is Flying Saucer?</h2>

<p>Flying Saucer is an XHTML renderer written in Java. It's 100% Java, not a
native wrapper, and it only handles valid XHTML + CSS. It is intended for
embedding web-based user interfaces into Java applications (ex. web photo album
generator, help viewer, iTunes Music Store clone). It cannot be used as a
general purpose webbrowser since it does not support the malformed legacy HTML
found on the web, though recent work on compatibility libraries may be enough to
do what you need. See JTidy integration</p>


<a name="legacy_html"></a>
<h2>Does Flying Saucer support legacy HTML?</h2>
<p>Flying Saucer is not an HTML component. It is a rendering component for XHTML
  content, but it cannot handle the malformed HTML 4.0 of general webpages,
  and it has no support for purely stylistic markup like FONT and CENTER. You
  have to use valid XHTML and CSS. For most embedded uses this is fine since
  the application author usually has control over the documents to be loaded.
  If you really need full IE/Mozilla/Safari like fidelity for general purpose
  webpages you should look into a webbrowser wrapper like <a href="https://jdic.dev.java.net/">JDIC's</a> Browser
  component.</p>
  
<!--
<h2>What about the JavaDoc browser?</h2>
<p>Okay, you got me. The JavaDoc browser reads the older, non-compliant html
  output of the javadoc program. This was accomplished using the JTidy parser
  and a newly developed compatibility library. Join the mailing list if you want
  more information. </p>
-->
  
<a name="web_browser"></a>
<h2>Is Flying Saucer a web browser?</h2>
<p>The core renderer just handles XHTML and CSS. It doesn't know anything about
  form submission, managing cookies, or tracking the browsing history. It
  just renders XHTML/CSS to the screen. However, Flying Saucer does include
  a Browser application which provides these features and more. You can use
  this as a good starting point for your own applications.</p>
  
  
  
<a name="applications"></a>
<h2>What kind of applications
can I use Flying Saucer for?</h2>
<p>Flying Saucer can be used for any Java application
  that requires some sort of styled text. This can be as simple as a chat program
  or as complicated as a complete ebook reader with dynamic stylesheets. Flying
  Saucer is very forward thinking and is designed to be a part of the next
  generation of applications that combine rich desktop clients with web content.
  Some examples of application types are:</p>

  <ul>
  <li>chat programs</li>
  <li>online music stores</li>
  <li>a Gutenberg eBook reader</li>
  <li>a distributed dictionary application</li>
  <li>Sherlock style map and movie
    search</li>
  <li><a href="http://www.konfabulator.com/">Konfabulator</a> and <a href="http://www.apple.com/macosx/tiger/dashboard.html">Dashboard</a> components</li>
  <li>an RSS reader</li>
  <li>a Friendster client</li>
  <li>an eBay client </li>
  <li>a splash screen</li>
  <li>an about box</li>
  <li>a helpfile viewer</li>
  <li>a javadoc viewer</li>
  <li>report generation and viewing</li>
  <li>a stock ticker / weather reporter<br>
    </li>
</ul>

<a name="xhtml_css_support"></a>
<h2>What XHTML/CSS features does Flying Saucer currently support?</h2>
<p>With our third release it supports most of
  the common XHTML and CSS features. This includes:</p>
<ul>
  <li>text and images (paragraphs, bold, italics, fonts, alignment, etc)</li>
  <li>the box model (borders, backgrounds, padding, margins)</li>
  <li>forms</li>
  <li>tables</li>
  <li>list items</li>
  <li>most CSS properties and shorthands</li>
  <li>float, absolute, relative, and fixed positioning support</li>
</ul>


<a name="xhtml_css_missing"></a>
<h2>What XHTML/CSS features is Flying Saucer missing?</h2>
<p>The only major feature missing as of R5 is the automatic table model (the
  old Netscape style of tables where the size of the content determined the size
  of the cells.) Fixed layout tables are supported. Other than that it's just a matter of squashing more bugs and getting more speed.</p>
<p>There is also no support for things outside the scope of XHTML/CSS such as Javascript, printing, Flash, SVG, or legacy
  HTML (though there is interest in all of those).</p>



<a name="hyperlinks"></a>
<h2>How do I make my program follow hyperlinks?</h2>

<p>You need a mouse listener that detects link clicks and does the 
HTTP request.  The XHTMLPanel includes a built in mouse listener to do this, but you can override it if you wish.</p>

<a name="forms_and_swing"></a>
<h2>How do I get access to the Swing components that make up my form fields?</h2>

<p> You can use the form accessor methods on the context. See 
<a href="gettingstarted.html#formaccess">Form Field Access</a> in the 
<a href="gettingstarted.html">Getting Started Guide</a>.<br>
</p>

<br/>
<br/>


<h3>Developer's FAQ</h3>

<a name="classpath"></a>
<h2>How do I set up my CLASSPATH?</h2>
<p>You only need the <code>core-renderer.jar</code> and the <code>ss_css2.jar</code>. That is all you need for your own programs. You also need an XML parser to be in your classpath, but this already included in recent versions of the JRE. To run the browser or use any of it's support classes you will need the <code>browser.jar</code> file.</p>



<a name="without_ant"></a>
<h2>How do I build XR without Ant? How do I build XR from within my IDE?</h2>
<p>Our Ant <code>build.xml</code> file includes all JAR files in the <code>/lib</code>
directory, plus the <code>/resources</code> directory tree in the classpath. The 
<b>compile</b> target also copies CSS and properties resources from <code>/src/css</code> and 
<code>src/conf</code> to <code>/build/resources</code>. If running from an IDE, you
will need to synchronize this yourself.</p>



<a name="configuration"></a>
<h2>How do I change the runtime configuration for XR?</h2>
<p>The renderer works with a simple, <code>java.util.Properties</code>-based 
configuration system--no XML! Our <code>org.xhtmlrenderer.util.Confuration</code> class 
loads properties on first access and makes them available at runtime.</p>

<p>When you are using the renderer, <code>Configuration</code> needs to know where
to find the properties file. If you are running from the renderer JAR file, our 
default properties will be read from there. If you have unpacked, or re-packed, 
the JAR, the location of the file is currently hard-coded as 
<code>/resources/conf/xhtmlrenderer.conf</code>. This path must be on the CLASSPATH
as it is loaded as a system resource using a ClassLoader. You need to add the parent
directory for <code>/resources</code> to your classpath, or include 
<code>/resources</code> in your JAR with no parent directory.</p>

<p>You can change the default properties for the application right in the <code>.conf</code> 
file. However, this is not a good idea, as you will have to merge your changes back on 
new releases. Plus, it will make reporting bugs more complicated. Instead, you can use 
one of two override mechanisms for changing the value of individual properties.</p>

<p><b>Override with Second Conf File:</b> Your override file should just re-assign 
values for properties originally given in <conf>xhtmlrenderer.conf</conf>. Please 
see the documentation in that file for a description of what each property affects.
As of R3, we look for a specific override file in a specific location, e.g.

<pre>$user.home/.flyingsaucer/local.xhtmlrenderer.conf</pre>

The <code>user.home</code> variable is a system property. If you call the 
<code>System.getProperty("user.home")</code> from within any Java program on your
machine, you will find out where this is. The location is usually 
<code>c:\Documents And Settings\{username}</code> and under the <code>/usr</code>
directory on UNIX systems. Try that method call to see where it is on your machine.
</p>


<p><b>Override with System Properties:</b> You can also override properties one-by-one
on the command line, using System properties. To override a property using the System 
properties, just re-define the property on the command line. e.g. 
<pre>
java -Dxr.property-name=new_value org.xhtmlrenderer.HTMLPanel
</pre>
</p>

<p>You can override as many properties as you like. Note that overrides are driven
by the property names in the default configuration file. Specifying a
property name not in that file will have no effect--the property will not be
loaded or available for lookup. Logging output is also controlled in this
Configuration file.</p>

<p>If you think an override is not taking, you can change the logging behavior
of the Configuration class. Because of inter-dependencies between Configuration
and the logging system, this is a special-case key, using the System property
<code>show-config</code>. The allowed values are from the 
<code>java.util.logging.Level</code> class. Use ALL to show a lot of detail about
Configuration startup, OFF for none, and INFO for regular output, like this
<pre>
java -Dshow-config=ALL org.xhtmlrenderer.HTMLPanel
</pre>
This will output messages to the console as Configuration is loading and looking
for overrides to the default property values for the renderer.
</p>

<p>We have just started using the Configuration system late in preparing release R4.
Some runtime behavior that should be configurable (like XHTML parser) is not. If you
would like to see some behavior made configurable, shoot us an email.</p>

<p>To access a parameter from Configuration at runtime, just use on of the many
static methods on the Configuration class. All of these just take the full name
of the property:
<ul>
	<li><code>String Configuration.valueFor(String)</code></li>
	<li><code>String Configuration.valueFor(String key, String default)</code></li>
	<li><code>byte Configuration.valueAsByte(String key, byte default)</code></li>
	<li><code>double Configuration.valueAsDouble(String key, double default)</code></li>
	<li><code>float Configuration.valueAsFloat(String key, float default)</code></li>
	<li><code>int Configuration.valueAsInt(String key, int default)</code></li>
	<li><code>long Configuration.valueAsLong(String key, long default)</code></li>
	<li><code>short Configuration.valueAsShort(String key, short default)</code></li>
	<li><code>boolean Configuration.isTrue(String key, boolean default)</code></li>
	<li><code>boolean Configuration.isFalse(String key, boolean default)</code></li>
</ul>
</p>

<a name="logging"></a>
<h2>How do I write to the log within XR?</h2>
<p>The renderer uses the <code>java.util.logging</code> package for logging information and 
exceptions at runtime. Logging behavior (output) is controlled via the main 
<a href="#configuration">configuration file</a>. The defaults may be overridden just like
any other configuration properties.</p>

<p>Please review the <code>java.util.logging</code> package docs before proceeding.</p>

<p>We log to a set of hierarchies. The internal code--everything between a request to load
a page and the page rendering--is logged to a subhierarchy of "plumbing", e.g. plumbing.load.
Our convention is that WARNING and SEVERE levels are very important and should always be
logged. INFO messages are useful and but can be excluded if you want a quiet ride. Anything
below INFO (FINE, FINER, FINEST) is generally only interesting for core renderer developers.
We don't guarrantee that anything below INFO will be useful, correct, practical or informative.
You can usually leave log levels at INFO for most purposes.</p>

<p>If you are modifying the renderer core code and want to add log messages, we recommend
you always use the <code>org.xhtmlrenderer.XRLog</code> class. Using this class ensures that
our log configuration is read properly before we write anything out to the log system.
The class is pretty self-explanatory, and all logging methods in it are static. If for some
reason you need to use the <code>java.util.logging.Logger</code> class directly, please
use <code>XRLog.getLogger()</code> to retrieve the instance to use.</p>

<!-- TODO: Update logging docs once we figure out how we will handle distribution log
controls versus dev log controls with override files. PW -->

</div>
</body>
</html>
